home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1999 July: Mac OS SDK / Dev.CD Jul 99 SDK1.toast / Development Kits / Mac OS / QuickTime / QuickTime 3 Interfaces & Libs / QTDevMac / CIncludes / QD3DExtension.h < prev    next >
Encoding:
C/C++ Source or Header  |  1998-08-21  |  10.2 KB  |  365 lines  |  [TEXT/MPS ]
  1. /*
  2.      File:        QD3DExtension.h
  3.  
  4.      Contains:    QuickDraw 3D Plug-in Architecture     Interface File.                                
  5.  
  6.      Version:    Technology:    Quickdraw 3D 1.5.4
  7.                  Release:    QuickTime 3.0
  8.  
  9.      Copyright:    © 1995-1998 by Apple Computer, Inc., all rights reserved.
  10.  
  11.      Bugs?:        Please include the the file and version information (from above) with
  12.                  the problem description.  Developers belonging to one of the Apple
  13.                  developer programs can submit bug reports to:
  14.  
  15.                      devsupport@apple.com
  16.  
  17. */
  18. #ifndef __QD3DEXTENSION__
  19. #define __QD3DEXTENSION__
  20.  
  21. #ifndef __QD3D__
  22. #include <QD3D.h>
  23. #endif
  24. #ifndef __QD3DERRORS__
  25. #include <QD3DErrors.h>
  26. #endif
  27.  
  28.  
  29.  
  30. #if PRAGMA_ONCE
  31. #pragma once
  32. #endif
  33.  
  34. #ifdef __cplusplus
  35. extern "C" {
  36. #endif
  37.  
  38. #if PRAGMA_IMPORT
  39. #pragma import on
  40. #endif
  41.  
  42. #if PRAGMA_STRUCT_ALIGN
  43.     #pragma options align=power
  44. #elif PRAGMA_STRUCT_PACKPUSH
  45.     #pragma pack(push, 2)
  46. #elif PRAGMA_STRUCT_PACK
  47.     #pragma pack(2)
  48. #endif
  49.  
  50. #if PRAGMA_ENUM_ALWAYSINT
  51.     #pragma enumsalwaysint on
  52. #elif PRAGMA_ENUM_OPTIONS
  53.     #pragma option enum=int
  54. #elif PRAGMA_ENUM_PACK
  55.     #if __option(pack_enums)
  56.         #define PRAGMA_ENUM_PACK__QD3DEXTENSION__
  57.     #endif
  58.     #pragma options(!pack_enums)
  59. #endif
  60.  
  61. /******************************************************************************
  62.  **                                                                             **
  63.  **                                Constants                                      **
  64.  **                                                                             **
  65.  *****************************************************************************/
  66. #if TARGET_OS_MAC
  67.  
  68. enum {
  69.     kQ3XExtensionMacCreatorType    = FOUR_CHAR_CODE('Q3XT'),
  70.     kQ3XExtensionMacFileType    = FOUR_CHAR_CODE('shlb')
  71. };
  72.  
  73. #endif  /* TARGET_OS_MAC */
  74.  
  75.  
  76. /******************************************************************************
  77.  **                                                                             **
  78.  **                                    Macros                                      **
  79.  **                                                                             **
  80.  *****************************************************************************/
  81.  
  82. /*
  83.  * Use this Macro to pack the version number for your class.  This would most
  84.  * likely get used in the  kQ3XMethodTypeObjectClassVersion to return the 
  85.  * version for your class.  This method is set up in your meta handler.
  86.  */
  87.  
  88. #define Q3_OBJECT_CLASS_VERSION(major, minor)            \
  89.     (unsigned long) (((major) << 16) | (minor))
  90.  
  91. /*
  92.  * Convenience macros to unpack a version number, accessing the major and the
  93.  * minor version numbers
  94.  */
  95. #define Q3_OBJECT_CLASS_GET_MAJOR_VERSION(version)        \
  96.     (unsigned long) ((version) >> 16)
  97.  
  98. #define Q3_OBJECT_CLASS_GET_MINOR_VERSION(version)        \
  99.     (unsigned long) ((version) & 0x0000ffff)
  100.  
  101.  
  102. /******************************************************************************
  103.  **                                                                             **
  104.  **                                Object Method types                              **
  105.  **                                                                             **
  106.  *****************************************************************************/
  107.  
  108. enum {
  109.     kQ3XMethodTypeObjectClassVersion = FOUR_CHAR_CODE('vrsn')
  110. };
  111.  
  112. typedef unsigned long                     TQ3XObjectClassVersion;
  113.  
  114. enum {
  115.     kQ3XMethodTypeObjectClassRegister = FOUR_CHAR_CODE('rgst')
  116. };
  117.  
  118. typedef CALLBACK_API_C( TQ3Status , TQ3XObjectClassRegisterMethod )(TQ3XObjectClass objectClass, void *classPrivate);
  119.  
  120. enum {
  121.     kQ3XMethodTypeObjectClassReplace = FOUR_CHAR_CODE('rgrp')
  122. };
  123.  
  124. typedef CALLBACK_API_C( void , TQ3XObjectClassReplaceMethod )(TQ3XObjectClass oldObjectClass, void *oldClassPrivate, TQ3XObjectClass newObjectClass, void *newClassPrivate);
  125.  
  126. enum {
  127.     kQ3XMethodTypeObjectClassUnregister = FOUR_CHAR_CODE('unrg')
  128. };
  129.  
  130. typedef CALLBACK_API_C( void , TQ3XObjectClassUnregisterMethod )(TQ3XObjectClass objectClass, void *classPrivate);
  131.  
  132. enum {
  133.     kQ3XMethodTypeObjectNew        = FOUR_CHAR_CODE('newo')
  134. };
  135.  
  136. typedef CALLBACK_API_C( TQ3Status , TQ3XObjectNewMethod )(TQ3Object object, void *privateData, void *parameters);
  137.  
  138. enum {
  139.     kQ3XMethodTypeObjectDelete    = FOUR_CHAR_CODE('dlte')
  140. };
  141.  
  142. typedef CALLBACK_API_C( void , TQ3XObjectDeleteMethod )(TQ3Object object, void *privateData);
  143.  
  144. enum {
  145.     kQ3XMethodTypeObjectDuplicate = FOUR_CHAR_CODE('dupl')
  146. };
  147.  
  148. typedef CALLBACK_API_C( TQ3Status , TQ3XObjectDuplicateMethod )(TQ3Object fromObject, const void *fromPrivateData, TQ3Object toObject, const void *toPrivateData);
  149. typedef CALLBACK_API_C( TQ3Status , TQ3XSharedLibraryRegister )(void );
  150. /******************************************************************************
  151.  **                                                                             **
  152.  **                            Object Hierarchy Registration                      **
  153.  **                                                                             **
  154.  *****************************************************************************/
  155. /*
  156.  *    Q3XObjectHierarchy_RegisterClass
  157.  *    
  158.  *    Register an object class in the QuickDraw 3D hierarchy.
  159.  *    
  160.  *    parentType            - an existing type in the hierarchy, or 0 to subclass
  161.  *                            TQ3Object
  162.  *    objectType            - the new object class type, used in the binary 
  163.  *                        metafile.  This is assigned at run time and returned
  164.  *                          to you.
  165.  *    objectName            - the new object name, used in the text metafile
  166.  *    metaHandler            - a TQ3XMetaHandler (may be NULL for some classes) 
  167.  *                          which returns non-virtual methods
  168.  *    virtualMetaHandler    - a TQ3XMetaHandler (may be NULL as well) which returns
  169.  *                            virtual methods a child would inherit
  170.  *    methodsSize            - the size of the class data needed (see 
  171.  *                            GetClassPrivate calls below)
  172.  *    instanceSize        - the size of the object instance data needed (see 
  173.  *                            GetPrivate calls below)
  174.  */
  175. EXTERN_API_C( TQ3XObjectClass )
  176. Q3XObjectHierarchy_RegisterClass (TQ3ObjectType         parentType,
  177.                                  TQ3ObjectType *        objectType,
  178.                                  char *                    objectName,
  179.                                  TQ3XMetaHandler         metaHandler,
  180.                                  TQ3XMetaHandler         virtualMetaHandler,
  181.                                  unsigned long             methodsSize,
  182.                                  unsigned long             instanceSize);
  183.  
  184. /*
  185.  *    Q3XObjectHierarchy_UnregisterClass
  186.  *    
  187.  *    Returns kQ3Failure if the objectClass still has objects 
  188.  * around; the class remains registered.
  189.  */
  190. EXTERN_API_C( TQ3Status )
  191. Q3XObjectHierarchy_UnregisterClass (TQ3XObjectClass     objectClass);
  192.  
  193. /*
  194.  *    Q3XObjectHierarchy_GetMethod
  195.  *    
  196.  *    For use in TQ3XObjectClassRegisterMethod call
  197.  */
  198. EXTERN_API_C( TQ3XFunctionPointer )
  199. Q3XObjectClass_GetMethod        (TQ3XObjectClass         objectClass,
  200.                                  TQ3XMethodType         methodType);
  201.  
  202. /*
  203.  *    Q3XObjectHierarchy_NewObject
  204.  *    
  205.  *    To create a new object. Parameters is passed into the 
  206.  *    TQ3XObjectNewMethod as the "parameters" parameter.
  207.  */
  208. EXTERN_API_C( TQ3Object )
  209. Q3XObjectHierarchy_NewObject    (TQ3XObjectClass         objectClass,
  210.                                  void *                    parameters);
  211.  
  212. /*
  213.  *    Q3XObjectClass_GetLeafType
  214.  *    
  215.  *    Return the leaf type of a class.
  216.  */
  217. EXTERN_API_C( TQ3ObjectType )
  218. Q3XObjectClass_GetLeafType        (TQ3XObjectClass         objectClass);
  219.  
  220. /*
  221.  *    Q3XObjectClass_GetVersion
  222.  *    This routine obtains the the version of a class, referenced by an
  223.  *    object class type.  Functions for getting the type are in QD3D.h,
  224.  *    if you have the class name.
  225.  */
  226. EXTERN_API_C( TQ3Status )
  227. Q3XObjectHierarchy_GetClassVersion (TQ3ObjectType         objectClassType,
  228.                                  TQ3XObjectClassVersion * version);
  229.  
  230. /*
  231.  *    Q3XObjectClass_GetType 
  232.  *
  233.  *    This can be used to get the type, given a reference 
  234.  *    to a class.  This is most useful in the instance where you register a 
  235.  *    an element/attribute and need to get the type.  When you register an
  236.  *    element, QD3D will take the type you pass in and modify it (to avoid
  237.  *    namespace clashes).  Many object system calls require an object type
  238.  *    so this API call allows you to get the type from the class referernce
  239.  *    that you will ordinarily store when you register the class.
  240.  */
  241. EXTERN_API_C( TQ3Status )
  242. Q3XObjectClass_GetType            (TQ3XObjectClass         objectClass,
  243.                                  TQ3ObjectType *        theType);
  244.  
  245.  
  246. EXTERN_API_C( TQ3XObjectClass )
  247. Q3XObjectHierarchy_FindClassByType (TQ3ObjectType         theType);
  248.  
  249.  
  250.  
  251. /*
  252.  *    Q3XObjectClass_GetPrivate
  253.  *    
  254.  *    Return a pointer to private instance data, a block of instanceSize bytes, 
  255.  *    from the Q3XObjectHierarchy_RegisterClass call.
  256.  *    
  257.  *    If instanceSize was zero, NULL is always returned.
  258.  */
  259. EXTERN_API_C( void *)
  260. Q3XObjectClass_GetPrivate        (TQ3XObjectClass         objectClass,
  261.                                  TQ3Object                 targetObject);
  262.  
  263. /*
  264.  * Return the "TQ3XObjectClass" of an object
  265.  */
  266. EXTERN_API_C( TQ3XObjectClass )
  267. Q3XObject_GetClass                (TQ3Object                 object);
  268.  
  269.  
  270.  
  271. /******************************************************************************
  272.  **                                                                             **
  273.  **                    Shared Library Registration Entry Point                      **
  274.  **                                                                             **
  275.  *****************************************************************************/
  276.  
  277. struct TQ3XSharedLibraryInfo {
  278.     TQ3XSharedLibraryRegister         registerFunction;
  279.     unsigned long                     sharedLibrary;
  280. };
  281. typedef struct TQ3XSharedLibraryInfo    TQ3XSharedLibraryInfo;
  282. EXTERN_API_C( TQ3Status )
  283. Q3XSharedLibrary_Register        (TQ3XSharedLibraryInfo * sharedLibraryInfo);
  284.  
  285. EXTERN_API_C( TQ3Status )
  286. Q3XSharedLibrary_Unregister        (unsigned long             sharedLibrary);
  287.  
  288.  
  289. /******************************************************************************
  290.  **                                                                             **
  291.  **                                Posting Errors                                  **
  292.  **                                                                             **
  293.  **            You may only call these functions from within an extension         **
  294.  **                                                                             **
  295.  *****************************************************************************/
  296. /*
  297.  *    Q3XError_Post
  298.  *    
  299.  *    Post a QuickDraw 3D Error from an extension.
  300.  */
  301. EXTERN_API_C( void )
  302. Q3XError_Post                    (TQ3Error                 error);
  303.  
  304. /*
  305.  *    Q3XWarning_Post
  306.  *    
  307.  *    Post a QuickDraw 3D Warning, from an extension.  Note the warning code you
  308.  *    pass into this routine must already be defined in the table above.
  309.  */
  310. EXTERN_API_C( void )
  311. Q3XWarning_Post                    (TQ3Warning             warning);
  312.  
  313. /*
  314.  *    Q3XNotice_Post
  315.  *    
  316.  *    Post a QuickDraw 3D Notice, from an extension.  Note the notice code you
  317.  *    pass into this routine must already be defined in the table above.
  318.  */
  319. EXTERN_API_C( void )
  320. Q3XNotice_Post                    (TQ3Notice                 notice);
  321.  
  322.  
  323. #if TARGET_OS_MAC
  324. /*
  325.  *    Q3XMacintoshError_Post
  326.  *    
  327.  *    Post the QuickDraw 3D Error, kQ3ErrorMacintoshError, and the Macintosh
  328.  *    OSErr macOSErr. (Retrieved with Q3MacintoshError_Get)
  329.  */
  330. EXTERN_API_C( void )
  331. Q3XMacintoshError_Post            (OSErr                     macOSErr);
  332.  
  333. #endif  /* TARGET_OS_MAC */
  334.  
  335.  
  336.  
  337. #if PRAGMA_ENUM_ALWAYSINT
  338.     #pragma enumsalwaysint reset
  339. #elif PRAGMA_ENUM_OPTIONS
  340.     #pragma option enum=reset
  341. #elif defined(PRAGMA_ENUM_PACK__QD3DEXTENSION__)
  342.     #pragma options(pack_enums)
  343. #endif
  344.  
  345. #if PRAGMA_STRUCT_ALIGN
  346.     #pragma options align=reset
  347. #elif PRAGMA_STRUCT_PACKPUSH
  348.     #pragma pack(pop)
  349. #elif PRAGMA_STRUCT_PACK
  350.     #pragma pack()
  351. #endif
  352.  
  353. #ifdef PRAGMA_IMPORT_OFF
  354. #pragma import off
  355. #elif PRAGMA_IMPORT
  356. #pragma import reset
  357. #endif
  358.  
  359. #ifdef __cplusplus
  360. }
  361. #endif
  362.  
  363. #endif /* __QD3DEXTENSION__ */
  364.  
  365.